AROS

The Amiga Replacement OS


(C) 1996 AROS - The Amiga Replacement OS


Chapter 3. Informations for Developers

3.1 Differences between AmigaOS and AROS

3.1.1 Pointer/Integer conversions

If you need a variable which can store a pointers as an integer, don't use ULONG but IPTR. AROS guarantees that LONG is 32bit on all systems, while IPTR is always large enough to contain a pointer. Most notable things which are affected by this: TagItems (the ti_Data field is now an IPTR instead of ULONG), BOOPSI classes (eg. the return value of DoMethod()), ReadArgs(), VPrintf(), VFPrintf() and more.

3.1.2 64bit variables

The type of 64bit variables is QUAD (unsigned: UQUAD). This is for example returned by the function SMult64() of utility.library. To access the high- and loworder 32bit values of the 64bit variable, use LOW32OF64() and HIGH32OF64() which are defined in AROS/include/aros/64bit.h.

3.1.3 Cloning RastPorts

AROS uses an external driver to access the graphics hardware. Since the nature of this driver is unknown to AROS, it is no longer valid to clone a RastPort by simply copying it. To be compatible, there are two new functions (in AROS) or macros (on Amiga): CreateRastPort(), CloneRastPort() and FreeRastPort(). You must call CloneRastPort() to create a copy or CreateRastPort() for an empty RastPort and FreeRastPort() after you´ve done your work with it.

This approach produces equivalent code on the Amiga but on AROS it can slow things down a bit. If you must preserve the original state of the RastPort, it's more safe to create a clone, work on it and then dispose of it again. It can also be faster if you would have to make a lot of changes to the RastPort to create two clones and set them to the two states you need. But your code should not depend on certain gains or losses of speed due to cloned RastPorts since the behaviour of the underlying graphics system is undefined.

3.1.4 Tag values

The original AmigaOS doesn't use the tags below USER_TAG (have a look at include:utility/tagitem.hif you don't belive me) which means, you shouldn't use tags at or near USER_TAG because then they might interfere with the OS's own tags. To solve this, AROS *does* use the tags *below* USER_TAG and the various implementators need not fear that their tags may overlap with the ones from the system. The file AROS/include/utility/tagitem.hnow contains the basic offsets for the various parts of the OS. In the future, it might be possible for users to allocate ranges of tags for specific uses.

3.1.5 DoMethod() or the stack is all wrong

There are CPUs around which don't care that the rest of the world have stacks which grow from large to small adresses. HPPA is an example for this. While it might look neat to the engineers who did it, it breaks our code. Another thing which breaks the code are small data types (eg. WORD, UBYTE, etc), because most systems put only integers or longs and pointers on the stack. So if some Msg structure expects WORD (see include:intuition/gadgetclass.h), this fails on every system but the Amiga. Then there are rumours about CPUs which use 32bit numbers and 64bit pointers or the other way round. On these CPUs, SetAttrs() and all other function which pass TagLists over the stack will fail. To overcome this, we introduce this rule:

To solve special problems on certain CPUs, we try to get a compiler which gets it right or, if that is impossible, we write a small preprocessor which replaces the dubious code by calls to the array versions.

3.1.6 Registers and CPUs

AROS has put some effort in defining a way to write code which is hardware independant. To achieve this, a couple of macros have been definied.

AROS_ASMSYMNAME(n)
Use this macro to access the assembler symbol n from C.

AROS_CSYMNAME(n)
Use this macro to access the C symbol n from assembler.

AROS_CDEFNAME(n)
Use this macro to define the assembler symbol n in such a way that it can be accessed from C.

AROS_SLIB_ENTRY(n,l)
Use this macro to get the name of a function n which is part of the shared library l.

AROS_UFH#(...)
Use this macro to declare a function which needs its arguments passed in registers. # is the number of arguments the function expects. The parameters of the macro are the return type of the function, its name and the parameters in AROS_UFHA() macros. If the function is an assembler function, you must use the AROS_ASMSYMNAME() macro to get it's name.

AROS_UFHA(t,n,r)
Use this macro to declare a parameter for a function which is declared with the AROS_UFH*() macro. It takes three arguments: The type of the parameter, the name of the parameter and the register the parameter is expected in.

AROS_UFC#(...)
Call a function which needs its arguments in registers. Works the same way as AROS_UFH*().

AROS_LH#[I](...)
Use this macro to declare a function which is part of a shared library. # is the number of arguments the function expects. If the function doesn't need the library base passed, you can speed up things by appending "I" to the macros name. The parameters of the macro are the return type of the function, its name, the parameters in AROS_LHA() macros, the type of the library, the name of the variable the library base is passed in, the offset in the function table (1 is the first offset and 5 is the first offset for a user function) and the name of the library.

AROS_LHA(t,n,r)
Use this macro to declare a parameter for a function which is declared with the AROS_LH*() macro. It takes three arguments: The type of the parameter, the name of the parameter and the register the parameter is expected in.

AROS_LC#[I](...)
Call a function which is part of a shared library. Works the same way as AROS_LH*().

AROS_STACK_GROWS_DOWNWARDS
has the value 1 if it is true and 0 otherwise.

AROS_BIG_ENDIAN
has the value 1 if the machine is big endian (eg. Amiga) or little endian (eg. PCs). Endianess means the way a number is stored in memory. Amiga stores 0x11223344 as 0x11 0x22 0x33 0x44 in memory while a PC does it as 0x44 0x33 0x22 0x11.

AROS_SIZEOFULONG
The result of sizeof(ULONG).

AROS_WORDALIGN
The minimal alignment of 16bit numbers in the memory of computer ( WORD and UWORD).

AROS_LONGALIGN
The minimal alignment of 32bit numbers in the memory of computer ( LONG and ULONG).

AROS_PTRALIGN
The minimal alignment of pointers in the memory of computer (eg. char * or APTR).

AROS_DOUBLEALIGN
The minimal alignment of 64bit IEEE floating point numbers in the memory of computer ( double).

AROS_WORSTALIGN
The worst possible alignment of any data type in the memory of computer (mostly the same as AROS_DOUBLEALIGN).

AROS_ALIGN(x)
Get the next possible address where one can put any data type. This macro will return x if any data type can be put at x. Most of the time, this macro is used like this: Get a buffer, put some data in it and then use AROS_ALIGN() to find out where the next data can be put.

AROS_SLOWSTACKTAGS
is defined, if you must use GetTagsFromStack() and FreeTagsFromStack() instead of just passing the address of the tag of the first tagitem.

AROS_SLOWSTACKMETHODS
is defined, if you must use GetMsgFromStack() and FreeMsgFromStack() instead of just passing the address of the method ID.

3.2 One for all and all for one - CVS

CVS is a software to maintain a database which contains the sources of a project one works on. The software offers a list of commands to merge the most recent version of the project with the local sources and to publish changes on has made over the Internet.

3.2.1 CVS on Un*x

If you have Linux or any other Un*x, then all you need is CVS 1.8 or better. If it's not already on your system (type cvs to find out), fetch if from one of the many GNU mirrors and install it in your $HOME.

Then get the AROS developer archive from the AmiNET and compile crypt.c(just say make crypt. Think of a good password and use cryptto encode it, like this:

Now skip the next section and read on in "How get access to the AROS CVS server".

3.2.2 CVS on Amiga

If you have an Amiga, you can participate, too. Just get the CVS from ADE, install it and get the demo for AmiTCP 4.0 ( AmiTCP-demo-40.lhain comm/tcp) from AmiNET. You also must have ixemul.library45.0 (should come with ADE) and ixnet.libraryin LIBS:. Then you can create your password with cryptout of the AROScrypt.lhaarchive from AmiNET (in dev/misc) like this:

(you must have the directory where crypt is stored in, in your path or you must do this in the same directory where crypt is).

CVS doesn't work with Miami. Miami uses a different routine for encrypting data than Un*x and therefore passwords generated with Miami won't work. Sorry.

3.2.3 How to get access to the AROS CVS server

Mail the password you have created to me: digulla@aros.fh-konstanz.de. The subject must be Access to AROS CVS Server and with this text in the mail:

Don't forget to fill in the information :-)

Wait until I confirm this. While you wait, look for CVS 1.8 or better if you haven't already done so.

3.2.4 Logging into the server

Before you can use any CVS commands, you must log into the server. To do this, use the CVS command "login":

where user is your login, eg. digulla:

This should ask you for your password. Type it in and if there is no error displayed, you are connected. If there is an error, try to omit the ":pserver:". If this still doesn't work, double check for typos and if you really, really, really can't find anything, then you got my email.

If the login has succeeded, then you can save you some typing by storing the argument to the -d option in the environment variable CVSROOT. Use

on Amiga or if you have a C shell (csh) and

for Bourne/Korn shells (bash, ksh).

On Amiga, you can make this permanent by copy env:CVSROOT envarc:, on Unix, you must add this to the shell's startup file ( .cshrc, .profile, .bashrc, .tcshrc, etc. Read the manual of your shell to find out). If you don't know what kind of shell you have, just try echo $SHELL or echo $shell. This should print the name of your shell.

If you haven't set this variable, you must add -d ... right after cvs in the following examples.

Now you can use any CVS command to get a copy of all AROS sources, update your sources or commit the changes you made.

3.2.5 How to get a copy of all AROS sources

Use the CVS checkout command for this:

This will create a directory AROS and populate it with all sources.

3.2.6 How to update the sources

If you have some sources and just want to update them, you can use the CVS update command. Change to the AROS directory and do this:

This should merge any changes that other users have made into your sources and create all new directories and files. If you and someone else has changed the same file, then CVS will try to merge the changes. That is, if he changed the first part and you the end of the file, CVS will do all the work for you. If there are changes which CVS can't resolve (eg. you said x--; and the other one x=x-1;), then CVS will put both versions in the file. Search for <<<< to find such problems.

You should do this before any commit in case this happens. So before you commit, do an update, call makeif any changes were made, fix the problems and then commit.

3.2.7 Committing changes

If you have changed a file, then you of course want to share your work with the other guys. To do this, use the CVS commit command:

You can specify a list of files after the commit or just do that in the AROS directory to commit all changes. CVS will then ask you what you did and send the changes to the CVS server for inclusion. Before you do that, you should always make an update (see the previous section) to avoid problems.

3.2.8 Creating new files and directories

You can also add new files or directories with the CVS add command:

or

Note that cvs add dir/file doesn't work. You can only add files in the current directory.

3.2.9 More infos about CVS

Well, CVS has man pages and info files and here is a nice link.

3.3 The jobserver

3.3.1 What is this ?

Well, it's more a task server. Its purpose is to allow multiple people to work at the same project at the same time without any two persons doing the same work twice. This is accomplished by the jobserver. It has a database with all tasks that are still to do, tasks that are currently under construction and tasks which are finished.

3.3.2 How does it work ?

Just send an EMail to

with the Subject: jobserv and in the body of the mail

It will list all commands that jobserv currently understands. Note that this is an automated service so the subject must match. jobserv ignores all lines in an email that it doesn't understand and stops reading at the first end or -- on a line of its own. jobserv will answer your EMails telling you what it did, what commands it did understand, which it did execute and which not and if not, why not. jobserv will also remember your EMail so others can see who added/requested/did which job - So don't worry you won't be credited for your work.

There is now a preliminary jobserver WWW interface:

3.3.3 Some commands the jobserver understands

add <id> <description>
Add a new job with the id <id> and the short text <description> as an explanation. <id> may contain any character except whitespace. Here is an example:

If the command was successful, the reply will tell you that a new job has been added to the database. If it wasn't successful, it will tell you why not (eg. because there is already a job with the same id).

req <id>
Allocate a task. This task will now be allocated by you. Your EMail will be stored with it so everyone can see who is working on that job and query you if you take too long or whatever.

done <id>
After you requested the job and finished it, you must tell jobserv that you're through.

show [free] [work] [done] [byme]
The most important command. It tells jobserv that you want to know what jobs are available and the like. All parameters are optional. "byme" is a flag which restricts the answer to jobs which match your EMail. The other flags are additive and restrict the reply to jobs which are still open, currently in progress or finished. So to see the jobs which were added and finished by you, use

Note that jobserv doesn't remember that you added a task if someone else allocated it. The most useful variants will be:

which shows everything that's still open and

which shows what jobs you did allocate and haven't finished yet.

prev up next

If you have comments or suggestions, email me at digulla@aros.fh-konstanz.de. 13. Aug 1997